package com.tgd.RingtoneContactManager;

/**
 * This interface will be used by the client to access information about a
 * contact.
 */
public interface Contact {
    /**
     * This enumeration is used to determine how the contacts should be
     * filtered.
     */
    static enum Filter {
        /**
         * Given to
         * {@link DAO#getContacts(DAO.Contact.Filter, DAO.Contact.Sort)} so the
         * returned list contains all contacts.
         */
        ALL,
        /**
         * Given to
         * {@link DAO#getContacts(DAO.Contact.Filter, DAO.Contact.Sort)} so the
         * returned list contains only contacts that have a custom ringtone
         * assigned.
         */
        CUSTOM,
        /**
         * Given to
         * {@link DAO#getContacts(DAO.Contact.Filter, DAO.Contact.Sort)} so the
         * returned list contains only contacts that have no custom ringtone
         * assigned.
         */
        DEFAULT,
        /**
         * Given to
         * {@link DAO#getContacts(DAO.Contact.Filter, DAO.Contact.Sort)} so the
         * returned list contains only contacts that have a custom ringtone
         * assigned that no longer exists.
         */
        DIRTY,
    }

    /**
     * This enumeration is used to determine how the contacts should be sorted.
     */
    static enum Sort {
        /**
         * Given to
         * {@link DAO#getContacts(DAO.Contact.Filter, DAO.Contact.Sort)} so the
         * returned list is sorted by the name of the contact. Sort order for 2
         * identical names is undefined.
         */
        NAME,
        /**
         * Given to
         * {@link DAO#getContacts(DAO.Contact.Filter, DAO.Contact.Sort)} so the
         * returned list is sorted by the name of the ringtone which each
         * contact uses. If two contacts use the same ringtone they are sorted
         * by the name of the contact.
         */
        RINGTONE,
    }

    /**
     * @return The id of the contact.
     */
    public String getId();

    /**
     * @return The name of the contact.
     */
    public String getName();

    /**
     * @return The {@link Ringtone} this contact is assigned, the default
     *         ringtone when a contact is set to use the default, or the default
     *         ringtone if the contact is assigned a non-existent ringtone.
     */
    public Ringtone getRingtone();

    /**
     * @return The id of the ringtone this contact is assigned. This will be an
     *         empty string {@code ""} when the contact is assigned to use the
     *         system default ringtone. In the case when a contact is assigned
     *         to a ringtone that no longer exists, the id of that non-existent
     *         ringtone will be returned.
     */
    public String getRingtoneId();

    /**
     * @return true if the contact is assigned a ringtone that does not exist.
     */
    public boolean isDirty();

    /**
     * @return true when this contact is set to use the system default ringtone.
     *         false otherwise. false when the user is assigned a ringtone that
     *         happens to be the system default.
     */
    public boolean isSetToDefault();
}

